From c736deb83b61c93ae02313728aaa83419a0e0386 Mon Sep 17 00:00:00 2001 From: Michael Catanzaro Date: Thu, 7 Jan 2021 11:18:34 -0600 Subject: [PATCH] Add section on GtkBuilder API changes to GTK 4 migration guide Thanks to Benjamin for helping with the language. --- docs/reference/gtk/migrating-3to4.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/reference/gtk/migrating-3to4.md b/docs/reference/gtk/migrating-3to4.md index 9112ec2132..32d2e94444 100644 --- a/docs/reference/gtk/migrating-3to4.md +++ b/docs/reference/gtk/migrating-3to4.md @@ -523,6 +523,25 @@ option. You should always review the resulting changes. The tag now supports for the 'lib' attribute the 'gtk' value only, instead of the 'gtk+' one previously. +## Adapt to GtkBuilder API changes + +gtk_builder_connect_signals() no longer exists. Instead, signals are +always connected automatically. If you need to add user data to your +signals, gtk_builder_set_current_object() must be called. An important +caveat is that you have to do this before loading any XML. This means if +you need to use gtk_builder_set_current_object(), you can no longer use +gtk_builder_new_from_file(), gtk_builder_new_from_resource(), or +gtk_builder_new_from_string(). Instead, you must use vanilla gtk_builder_new(), +then call gtk_builder_set_current_object(), then load the XML using +gtk_builder_add_from_file(), gtk_builder_add_from_resource(), or +gtk_builder_add_from_string(). You must check the return value for +failure and manually abort with g_error() if something went wrong. + +You only have to worry about this if you were previously using +gtk_builder_connect_signals(). If you are using templates, then +gtk_widget_init_template() will call gtk_builder_set_current_object() +for you, so templates work like before. + ### Adapt to event controller API changes A few changes to the event controller and #GtkGesture APIs -- 2.30.2